home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / ams__l~1.zoo / man / resoluti.man < prev    next >
Encoding:
Text File  |  1993-09-05  |  4.5 KB  |  142 lines
  1.                         ATARI MACHINE SPECIFIC LIBRARY
  2.  
  3.  
  4.  
  5. NAME
  6.      Resolution - support for the currently defined Atari resolutions
  7.  
  8. SYNOPSIS
  9.      #include <Resolution.h>
  10.  
  11.      class Resolution
  12.  
  13.      extern const Resolution STLow;
  14.      extern const Resolution STMedium;
  15.      extern const Resolution STHigh;
  16.  
  17.      extern const Resolution TTLow;
  18.      extern const Resolution TTMedium;
  19.      extern const Resolution TTHigh;
  20.  
  21.  
  22. DESCRIPTION
  23.      When writing machine specific graphical programs, the Atari
  24.      programmer may prefer to increase efficiency by coding specifically
  25.      for one or more of the computer's resolutions.  For example, games
  26.      are often written to support only colourful resolutions.
  27.  
  28.      The start-up resolution is always restored upon termination.
  29.  
  30.      Note that the resolutions of the Falcon030 are not yet supported,
  31.      but that this module has been designed with extensions for that
  32.      machine in mind.  Support will be available as soon as an author
  33.      has a Falcon030!
  34.  
  35. CLASSES
  36.      A Resolution is a (Width,Height,Depth) triple.  Width is the
  37.      number of pixels in the horizontal dimension (ie. number of columns).
  38.      Height is the number of pixels in the vertical dimension (ie. the number
  39.      of lines).  Depth is the number of bitplanes.  A resolution will have
  40.      a number of colours equal to 2 to the power of the number of bitplanes
  41.      (colours = power(2,bitplanes)).
  42.  
  43. CLASS MEMBERS
  44.   Resolution::
  45.      Resolution()
  46.        - Creates a Resolution equal to the resolution currently in use.
  47.          (because of start-up conditions or because of another Resolution
  48.           beging "Used")
  49.  
  50.      Resolution(int width, int height, int depth)
  51.        - Create a Resolution with the given attributes.
  52.  
  53.      int Width() const
  54.      int Height() const
  55.      int Depth() const
  56.        - Examine resolution properties.
  57.  
  58.      void Use() const
  59.        - Mofiy the system to enable this resolution.
  60.  
  61.      short BitPlanes() const
  62.        - Equivalent to Depth().
  63.  
  64.      short BytesPerBitPlaneLine() const
  65.        - The amount of memory used by one line of a single bitplane.
  66.  
  67.      short BytesPerLine() const
  68.        - The amount of memory used by one line of all bitplanes.
  69.  
  70.      int NumberOfColours() const
  71.        - The number of colours - power(2,Depth()), but efficient.
  72.  
  73.      int operator==(const Resolution&) const
  74.      int operator!=(const Resolution& R) const
  75.        - Compare resolutions.  They are considered equal if the 
  76.          (Width,Height,Depth) components are equal.
  77.  
  78.      The following functions should be avoided.  They are only intended
  79.      to simplify implementation of old-style resolutions - where a "mode"
  80.      of 0, 1, 2, etc. determined the (Width,Height,Depth) values.  This
  81.      is not feasible on the Falcon030.
  82.  
  83.      Resolution(short)
  84.      short OldMode() const
  85.        - as per Getrez(), but -1 if not possible.
  86.  
  87.  
  88. USAGE
  89.      When a program only supports certain resolutions, the programmer
  90.      should either change to an appropriate resolution, or warn the
  91.      user and exit.
  92.  
  93.      Note that if you attempt to change to a colour resolution on an
  94.      Atari ST[e] while in monochrome, the computer will reboot.  On the
  95.      TT, the change occurs fine, but the general approach should be to
  96.      never automatically change to ANY resolution when starting in STHigh
  97.      or even perhaps TTHigh (which also uses a non-colour monitor).
  98.  
  99. EXAMPLES
  100.      A sample start to a program may be:
  101.  
  102.      {
  103.          Resolution InitialResolution;
  104.  
  105.          // Only support the 16-colour modes
  106.          if (InitialResolution == STHigh || InitialResolution == TTHigh) {
  107.              printf("Sorry, only 16-colour modes\n");
  108.              exit(1);
  109.          }
  110.  
  111.          if (InitialResolution == TTLow)
  112.              TTMedium.Use();
  113.          else if (InitialResolution != TTMedium)
  114.              STLow.Use();
  115.  
  116.          ...
  117.      }
  118.  
  119.  
  120. SEE ALSO
  121.      Screen
  122.  
  123. BUGS
  124.      GEM/AES still ignores resolution changes.
  125.      Note that due to the fascist way TOS changes resolution, the current
  126.      logical screen is cleared when the current resolution is changed.
  127.  
  128. AUTHOR
  129.      Warwick Allison, 1992.
  130.      warwick@cs.uq.oz.au
  131.  
  132. COPYING
  133.      This functionality is part of the Atari Machine Specific Library,
  134.      and is Copyright 1992 by Warwick W. Allison.
  135.  
  136.      The Atari Machine Specific Library is free and protected under the
  137.      GNU Library General Public License.
  138.  
  139.      You are free to copy and modify these sources, provided you acknowledge
  140.      the origin by retaining this notice, and adhere to the conditions
  141.      described in the GNU LGPL.
  142.